Greptile Summary

This PR consolidates 3 separate regex patterns and handlers in doclinks into 2 unified handlers, eliminating ~40 lines of duplicated candidate resolution logic. The refactor extends validation from only .md links to ALL file links (.py, directories, etc.) and adds path-similarity-based disambiguation when multiple candidates match.

Key improvements:

• Merged doc_pattern + md_link_pattern into single link_pattern + replace_link_match handler
• Extracted resolve_candidates() helper with pick_best_candidate() scoring by directory overlap
• Validates ALL file links (not just .md) with appropriate fallback search
• Shares single git ls-files call between both index builders (eliminates double subprocess call)
• Expanded extract_other_backticks filter from 1 to 18 file extensions
• Moved import time to top-level (was incorrectly inside watch loop)
• Deleted duplicate docs/usage/transports.md (nearly identical to docs/usage/transports/index.md)

The refactor is backward-compatible and all existing behaviors are preserved. The 9 new tests provide comprehensive coverage of the disambiguation logic, link validation, and edge cases.

Confidence Score: 5/5

• This PR is safe to merge with high confidence
• The refactor is well-tested (56 tests, +9 new), eliminates code duplication, and is explicitly backward-compatible. The disambiguation logic is sound and the PR description claims all tests pass. Documentation changes are mechanical link fixes.
• No files require special attention

Important Files Changed

Flowchart

%%{init: {'theme': 'neutral'}}%%
flowchart TD
    A[process_markdown] --> B{Split by ignore regions}
    B --> C[Process each region]
    C --> D{Apply code_pattern}
    D --> E[replace_code_match]
    E --> F{File has extension or /?}
    F -->|No| G[Skip]
    F -->|Yes| H[file_index lookup]
    H --> I[resolve_candidates]
    I --> J{Candidates count}
    J -->|0| K[Error: not found]
    J -->|1| L[Use single match]
    J -->|Multiple| M[pick_best_candidate]
    M --> N{score_path_similarity}
    N -->|Unique max| O[Use best match]
    N -->|Tie| P[Error: ambiguous]
    
    C --> Q{Apply link_pattern}
    Q --> R[replace_link_match]
    R --> S{Link type?}
    S -->|.md placeholder| T[doc_index lookup]
    S -->|Absolute path| U{File exists?}
    S -->|Relative path| V{File exists?}
    S -->|URL/anchor| W[Skip]
    
    T --> I
    U -->|No| X[_search_fallback]
    V -->|No| X
    X --> Y{Has extension?}
    Y -->|.md| Z[doc_index search]
    Y -->|Other| AA[file_index search]
    Z --> I
    AA --> I

_{Last reviewed commit: 4a6848b}

Looks good, but it would be nice to have a test which fails if there are invalid links in .md files.

Looks good, but it would be nice to have a test which fails if there are invalid links in .md files.

yeah pre-commit hooks will fail you on this since they run doclinks on all files